---
title: Configurer Astro
i18nReady: true
---
import ReadMore from '~/components/ReadMore.astro'

Personnalisez le fonctionnement d'Astro en ajoutant un fichier `astro.config.mjs` dans votre projet. C'est un fichier commun dans les projets Astro, et tous les exemples officiels de modèles et de thèmes sont livrés avec un fichier par défaut.

<ReadMore>Lisez la [doc de référence de l'API d'Astro](/fr/reference/configuration-reference/) pour une vue d'ensemble de toutes les options de configuration supportées.</ReadMore>

## Le Fichier de Configuration d'Astro

Un fichier de configuration Astro valide exporte sa configuration en utilisant l'export `default`, en utilisant l'aide `defineConfig` recommandée :

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  // vos options de configuration ici...
  // https://docs.astro.build/fr/reference/configuration-reference/
})
```

L'utilisation de `defineConfig()` est recommandé pour obtenir l'aide sur les types utilisés dans votre éditeur de code (IDE), mais elle est aussi optionnelle. Un fichier de configuration minimal valide pourrait ressembler à ça :

```js
// Exemple : Fichier de configuration minimal, vide
export default {}
```

## Types de Fichier de Configuration Supportés

Astro supporte plusieurs formats de fichiers pour son fichier de configuration JavaScript : `astro.config.js`, `astro.config.mjs`, `astro.config.cjs` et `astro.config.ts`. Nous recommandons d'utiliser `.mjs` dans la plupart des cas où `.ts` si vous voulez écrire du TypeScript dans votre fichier de configuration.

Le chargement du fichier de configuration TypeScript est géré par [`tsm`](https://github.com/lukeed/tsm) respectera les options tsconfig de votre projet.
## Résolution du fichier de configuration

Astro va automatiquement essayer de résoudre un fichier de configuration nommé `astro.config.mjs` à la racine du projet. Si aucun fichier de configuration n'est trouvé à la racine de votre projet, les options par défaut d'Astro seront utilisées.

```bash
# Exemple : Lit votre configuration à partir de ./astro.config.mjs
astro build
```

Vous pouvez explicitement définir un fichier de configuration à utiliser avec l'option `--config` depuis l'interface de commande en ligne CLI. Cette option est toujours relative au répertoire de travail actuel dans lequel vous avez lancé la commande `astro`.

```bash
# Exemple : Lit votre configuration à partir de ce fichier
astro build --config mon-fichier-config.js
```

## Autocomplétion de configuration

Astro recommande d'utiliser l'aide `defineConfig()` dans votre fichier de configuration. `defineConfig()` fournit une autocomplétion automatique dans votre IDE. Les éditeurs comme VSCode sont capables de lire les définitions de type TypeScript d'Astro et de fournir des indications de type JSDoc automatiques, même si votre fichier de configuration n'est pas écrit en TypeScript.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  // vos options de configuration ici...
  // https://docs.astro.build/fr/reference/configuration-reference/
})
```

Vous pouvez également fournir des définitions de type manuellement à VSCode, en utilisant cette notation JSDoc :

```js
// astro.config.mjs
 export default /** @type {import('astro').AstroUserConfig} */ ({
  // vos options de configuration ici...
  // https://docs.astro.build/fr/reference/configuration-reference/
}
```

## Référencement des fichiers relatifs

Si vous fournissez un chemin relatif à `root` ou à l'option `--root`, Astro résoudera ce chemin par rapport au répertoire de travail actuel où vous avez lancé la commande `astro`.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  // Cherches vers le répertoire "./foo" dans le répertoire de travail actuel
  root: 'foo'
})
```

Astro va chercher toutes les autres chaînes relatives de fichiers et de répertoires par rapport à la racine du projet :

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  // Se dirige vers le répertoire "./foo" dans le répertoire de travail actuel
  root: 'foo',
  // Se dirige vers le répertoire "./foo/public" dans le répertoire de travail actuel
  publicDir: 'public',
})
```

Pour référencer un fichier ou un répertoire relatif au fichier de configuration, utilisez `import.meta.url` (sauf si vous écrivez un fichier common.js `astro.config.cjs`).

```js "import.meta.url"
// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  // Se dirige vers le répertoire "./foo", relatif à ce fichier de configuration
  root: new URL("./foo", import.meta.url).toString(),
  // Se dirige vers le répertoire "./public", relatif à ce fichier de configuration
  publicDir: new URL("./public", import.meta.url).toString(),
})
```

:::note
Les propriétés `import.meta` spécifiques à Vite, comme `import.meta.env` ou `import.meta.glob`, ne sont _pas_ accessibles depuis votre fichier de configuration. Nous recommandons des alternatives comme [dotenv](https://github.com/motdotla/dotenv) ou [fast-glob](https://github.com/mrmlnc/fast-glob) pour ces cas d'utilisation respectifs. En outre, [les alias de chemin tsconfig](https://www.typescriptlang.org/tsconfig#paths) ne seront pas résolus. Utilisez des chemins relatifs pour les importations de modules dans ce fichier.
:::

## Personnalisation des noms de fichiers de sortie

Pour le code qu'Astro traite, comme les fichiers JavaScript ou CSS importés, vous pouvez personnaliser les noms de fichiers de sortie en utilisant [`entryFileNames` (EN)](https://rollupjs.org/guide/en/#outputentryfilenames), [`chunkFileNames` (EN)](https://rollupjs.org/guide/en/#outputchunkfilenames), et [`assetFileNames` (EN)](https://rollupjs.org/guide/en/#outputassetfilenames) dans une entrée `vite.build.rollupOptions` de votre fichier  `astro.config.*`.

```js ins={9-11}
// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: 'entry.[hash].mjs',
          chunkFileNames: 'chunks/chunk.[hash].mjs',
          assetFileNames: 'assets/asset.[hash][extname]',
        },
      },
    },
  },
})
```

Cela peut être utile si vous avez des scripts dont les noms peuvent être affectés par des bloqueurs de publicité (par exemple `ads.js` ou `google-tag-manager.js`).

## Variables d'Environment
Astro évalue les fichiers de configuration avant de charger vos autres fichiers. Ainsi, vous ne pouvez pas utiliser `import.meta.env` pour accéder aux variables d'environnement qui ont été définies dans les fichiers `.env`. 

Vous pouvez utiliser `process.env` dans un fichier de configuration pour accéder à d'autres variables d'environnement, comme celles [définies par le CLI](/fr/guides/environment-variables/#utilisation-en-cli).

Vous pouvez également utiliser l'[aide `loadEnv` de Vite (EN)](https://main.vitejs.dev/config/#using-environment-variables-in-config) pour charger manuellement les fichiers `.env`.

:::note
`pnpm` ne vous permet pas d'importer des modules qui ne sont pas directement installés dans votre projet. Si vous utilisez `pnpm`, vous devrez installer `vite` pour utiliser l'aide `loadEnv`.
```sh
pnpm add vite --save-dev
```
:::

```js title="astro.config.mjs"
import { loadEnv } from "vite";
const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");
```

## Référence de configuration

<ReadMore>Lisez la documentation de référence [sur la configuration de l'API d'Astro](/fr/reference/configuration-reference/) pour une vue d'ensemble des options de configuration supportées.</ReadMore>
